Connector for VMware vCenter Configuration Manager

This section of the documentation contains technical information on the ASM Core to VMware vCenter Configuration Manager Connector, including:

  • The name of the .NET assembly file
  • The connection methodology
  • The resource and link types that can be discovered
  • The events that are generated
  • The actions that can be called under workflow control

For compatibility and version support details, refer to the ASM Connector Matrix.

You should familiarize yourself with the information in Installing Connectors before installing any connectors, and read the Integration topics for more information on how to configure them.

Functionality

The VMware vCenter Configuration Manager connector allows organizations to enhance the following processes:

  • Incident Management. Automatically discover machine resources into the ASM Core Federated CMDB for the purposes of incident classification, reporting, and routing.
  • Asset Management. Automatically discover installed software into the ASM Core Federated CMDB for the purposes of comparing the actual deployments of software with software license assignments.
  • Change Management. Automatically enforce the initiation of a formal Change Management process in ASM Core whenever a server administrator attempts to roll out changes (eg: Windows service packs or security bulletins) using VMware vCenter Configuration Manager.

Licensing

Contact Sales for more information.

The connector for VMware vCenter Configuration Manager is not separately licensed and is available to any organization that is licensed for ASM Core. On the VMware vCenter Configuration Manager side, the “integration” license is required.

Connector Details

Information fields

Description

Connector

VMware vCenter Configuration Manager <-> ASM Core

ASM Core

v10 and above

Third-party application

VMware vCenter Configuration Manager

Assembly

Infra.Connector.vCM.dll

Configuration file

Infra.Connector.vCM.icnf

Connection methodology

Database

Connector Installation

The steps below detail how to install the connector.

  1. Download the connector zip package, save it in a temporary directory then unzip it.
  2. The unzip folder should contain 4 sub-folders: Bin, Config, Doc, and vCM Scripts.
  3. Prepare the vCM Database. SeevCM Database Preparation.
  4. Prepare the ASM Core Server. SeeASM Core Server Preparation.
  5. Configure a Connection Source. SeeConnection Source Creation.

vCM Database Preparation

A number of operations must be performed against the vCM database server as part of the connector installation. These operations must be performed by an account that is a database owner of the target database catalog such that any objects created in these steps should be created in the “dbo” schema.

Some of these operations are performed by shipped database script files (*.sql). Others should be performed by the SQL Server administration interface.

The connector connects solely to the main vCM database catalog. By default this will be called “VCM”; in some upgraded environments this may be “SCM” or “ECM”.

vCM utilizes additional database catalogs with suffixed names e.g.“VCM_Unix” and “VCM_Coll”. The database account used by the connector requires some access to one of these, the “Unix” database. However, the connector will never connect to this database directly.

  1. Copy the contents of the vCM Scripts directory to your vCM database server.
  2. Login to the SQL Server administration interface as an administrator.
  3. Create a dedicated database login for the ASM connector.
  4. On the main database catalog:
    • Run the provided SQL script Create_vSM_Connector_Objects.sql.
      (This creates the stored procedure used by the connector.)
    • Run the provided SQL script Grant_vSM_Connector_Access_Main.sql.
      (This creates the vSM_Connector database role and assigns it permissions.)
    • Add the dedicated login as a user to the catalog
    • Add the user as a member to the database role vSM_Connector.
    • Run the provided SQL script Enable_vCM_Integration.sql.
      (This enables vCM to create RFC events.)
  5. On the “Unix” database catalog:
    • Run the provided SQL script Grant_vSM_Connector_Access_Unix.sql.
    • Run the provided SQL script Grant_vSM_Connector_Access_Unix.sql.
      (This creates the vSM_Connector database role and assigns it permissions.)
    • Add the dedicated login as a user to the catalog
    • Add the user as a member to the database role vSM_Connector.

Maintenance

If required at a later date, RFC events can be disabled by running the database script Disable_vCM_Integration.sql.

ASM Core Server Preparation

  1. Copy the contents of the bin and config directories to the following locations on the ASM Core server:

    2. File Name

    Target Location(s)

    bin / Infra.Connector.vCM.dll

    < ASM Root>

    <Target System>/bin

    config / Infra.Connector.vCM.icnf

    <Target System>/config

    config / Infra.Connector.vCM.Install.scp

  1. In the ASM Core Server Console, execute the SQL script Infra.Connector.vCM.Install.scp against the target system.

Restart the following Windows services:

  • The World Wide Web Publishing Service
  • The ASM Connector Service

Connection Source Creation

When creating a new VMware vCenter Configuration Manager source from the Source option of the Integration Platform, some specific parameters have to be entered as follows:

DB Connection String

Identifies the database server and catalog using an ADO.NET Native SQL Server Client connection string, minus explicit credentials.

 

E.g. Server=server-host-name-instance-name;Database=vCM

DB User ID

The login id of the database user assigned to ASM Core.

DB Password

The password of the database user.

 

Two modes of authentication against the database are supported:

  • SQL Server Authentication
  • Integrated Windows Authentication

In SQL Server Authentication the connector uses the credentials of a user created within the database. In this scenario, the credentials of that user are specified within the “DB User ID” and “DB Password” parameters.

In Integrated Windows Authentication the connector is authenticated using the credentials of a Windows account granted permission to the database. When this method is used the “DB User ID” and “DB Password” parameters are ignored and should be left blank. Instead, connector is authenticated using the account of the executing process. To use this mode of authentication:

  1. The “DB Connection String” parameter requires an addition suffix, “;Integrated Security=SSPI”.
    E.g. Server=server-name;Database=main;Integrated Security=SSPI
    Where main is the name of the main database (see previous explanations about main vCM database).
  2. The following processes must be configured to execute using a Windows account with the prerequisite database permissions.
    • The IIS Application Pool used by the ASM Core virtual directory (directories)
    • The various ASM Core Windows services

A common mistake users make when configuring Integrated Windows Authentication is to only configure the account for one of the required processes. If the IIS Application Pool is configured with the correct account but the ASM Core Windows services are not, users may be confused as the connection will succeed within main application but background tasks such as scheduled FCMDB scans will fail.

Incident Management

The VMware vCenter Configuration Manager connector allows you to populate your Federated CMDB with machines (ie: physical servers, virtual servers, desktops, and laptops) for the purposes of incident classification, reporting, and routing.

Resource Types

Machine

A resource that represents a single computer.

Field

Data Type

Machine ID

Int

Machine Name

String

Domain Name

String

Manufacturer

String

Model

String

Primary User

String

Primary User NT Domain

String

Primary User NT Login

String

Last Rebooted

date/time

Is Managed by vCM

Boolean

Is VM

Boolean

OS Name

string

OS Vendor

string

OS Version

string

Time Zone

string

Machine Type

string

Recommended Configuration

Resources

We recommend that you:

  • Create a Machine CMDB Item Type and design a screen for it.
  • Create a Machine Template Eg:
  • Set up a resource mapping in the Integration Platform to map vCM Machine resources and attributes onto ASM Core Machine CIs. The key fields to consider mapping are:

ASM Core Machine CI Attribute

Possible sources from the vCM Machine Resource

Ref

Machine ID

Title

Machine Name

User

 The connector dissects the “Primary User” field published by vCM into NT Domain and User ID components. These are provided to enable you to derive the “User” field of an imported Configuration Item using a Resolution Rule. If the ASM System is also integrated with Active Directory, these dissected fields can be matched to the “NT Domain Name” and “NT User ID” of an imported User. The criteria for such a resolution rule should be defined as follows:

{Person:NT Account Name} = {Resource:Primary User NT User Login}

AND {Person:NT Domain Name} = {Resource:Primary User NT Domain Name}

The “Primary User” presented by vCM may not necessarily correspond to the “User”, or may not be populated at all. If this is a concern, use discrepancy reporting on this field to monitor changes to this value.

You may also consider mapping other attributes such as Manufacturer, Model, OS Vendor, OS Name, and OS Version which can be useful for incident diagnosis, routing, and reporting purposes.

Software License Management

The VMware vCenter Configuration Manager connector allows you to populate your Federated CMDB with the software actually installed on each machine. This is intended to be used in conjunction with the Asset Management capabilities of ASM Core, which are used to maintain your inventory of software licenses and their current assignments. By comparing the software actually installed on machines with the current license assignments, you can determine whether you are under or over licensed.

Resource Types

Windows Software

A resource that represents a specific minor version of a Windows software product that is installed on one or more machines.

 

Field

Data Type

Product Key

String

Product Name

String

Product Version

String

Major Version

String

Minor Version

String

Publisher

string

Unix Software

A resource that represents a specific minor version of a UNIX software product that is installed on one or more machines.

Field

Data Type

Product Key

string

Product Name

string

Product Version

string

Major Version

string

Minor Version

string

Long Name

string

Description

String

Category

String

Link Types

Windows Software Installed On

A relationship between a Machine resource and a Windows Software resource indicating that the software is installed on that machine.

Resource Type A

Machine

Resource Type B

Windows Software

 

Field

Data Type

Date Installed

date/time

Date Collected

date/time

Date Last Used

date/time

Frequency

string

Install Source

string

Unix Software Installed On

A relationship between a Machine resource and a UNIX Software resource indicating that the software is installed on that machine.

Resource Type A

Machine

Resource Type B

Unix Software

 

Field

Data Type

Date Installed

date/time

Date Collected

date/time

Date Last Used

date/time

Recommended Configuration

Resources

It is recommended to either:

  • Store both Windows and UNIX software in the in-built Software Product CMDB Item type.
  • Create separate descendent CMDB Item Types for Windows Software and UNIX Software.

It is recommended to map the VCM Resource attribute Product Name to the ASM Core Configuration Item attribute Title.

There are three possible ways to manage versions of software products in the CMDB as follows:

  • Each software product is stored as a single Configuration Item. To support this scenario, set up a Matching Rule based on:
  • Product Name
  • Each major version of a software product is stored as a single Configuration Item. To support this scenario, add a Major Version attribute to your CMDB Item and set up a Matching Rule based on:
    • Product Name
    • Major Version
    •  

  • Each minor version of a Software Product is stored as a single Configuration Item. To support this scenario, add Major Version and Minor Version attributes to your CMDB Item and set up a Matching Rule based on:
    • Product Name
    • Major Version
    • Minor Version

The appropriate approach should be determined based on the granularity of tracking desired. By setting up Criteria in combination with Matching Rules it is possible to track different Software Products at different levels. As per any kind of matching configuration in ASM Core, users are advised to regulate ambiguous and non-matching resources to ensure flawed data is handled sensibly.

Links

It is recommended that the Installed On links be imported using a special link type such as:

  • Category should be set to Summary. A single machine may have a large number of software products installed; similarly, a single software product may be installed on a very large number of machines. Therefore, rendering software installations in a CMDB linking can greatly reduce the readability of the CMDB Linking diagram and obfuscate those relationships that should be clearly visible in the diagram. This configuration is used to hide software installations on the diagram allowing more significant impact relationships to be more clearly presented.
  • Principal should be set to the CMDB Item Type of the machine CMDB Items imported from vCM, or a common ancestor thereof. This could be as simple as Configuration Item. Optionally, it can be helpful to specify a descriptive role name for Principal such as Installed On.
  • Summarized should be set to Software Product or whatever descendent type is being assigned to your software product CMDB Items imported from vCM. Optionally, it can be helpful to specify a descriptive role name for Summarized such as Installed Software.

Change Management

The VMware vCenter Configuration Manager connector allows you to automatically enforce the initiation of a formal Change Management process in ASM Core whenever a server administrator attempts to roll out changes (eg: Windows service packs or security bulletins) using VMware vCenter Configuration Manager.

Event Types

RFC Event

An RFC Event represents a notification that a job has been created within vCM to affect some change in the environment that needs to be approved in order to proceed.

The event type exposes the following fields:

Field

Data Type

Description

RFC Event GUID

String

The unique identifier of the job with VCM.

Notes

String

Any notes the VCM administrator has entered to describe the change.

Type

String

The type of job as characterized by VCM.

Run Now

Boolean

A flag indicating whether the VCM administrator plans to run the job immediately or not.

Run Time

date/time

The date/time at which the VCM administrator plans to run the job.

Machine CIs

Reference to zero or more Machine resources

The list of machines that will be impacted by the job, for impact analysis purposes.

Machine CI Ids

String

A textual representation of above.

Event ID

String

The ASM Core request/call ID (will be automatically updated by the connector).

RFC No

String

The ASM Core RFC number (will be automatically updated by the connector).

RFC Status

String

The status of the job. Will initially be “Pending” when the event is received.

Outbound Actions

The two Outbound Actions published by the connector are:

  • Approve Change. This action allows a change (as identified by a previous event) to proceed.
  • Deny Change. This action stops a change (as identified by a previous event) from proceeding.

Both actions have the same parameters as follows:

Input Parameters

Field

 Data Type
RFC Event GUID string
RFC No string
RFC Status String
RFC Notes String

Output Parameters

The same fields exposed during receipt of the initial event are available as parameters from actions.

Error Handling

All outbound actions in the connector are attempted synchronously, with one of the following three outcomes possible:

Success

Outbound Action tasks that are created and complete successfully will activate the Completion branch of the workflow.

Failure to Create

Outbound Action tasks that cannot be created due to a soft error (for example, if they cannot connect to the VCM database), will remain active and open. Such tasks will be subject to the retry and email notification parameters as defined in the connection source.

Failure to Complete

Outbound Action tasks that cannot be completed due to a hard error (for example, if the GUID field is not mapped), will cause the Not Completed branch of the workflow. Possible completion errors are:

  • RFC Event GUID Not Mapped
  • RFC Event GUID Empty
  • RFC Event GUID Invalid

Recommended Configuration

At a high level, the steps involved in setting up Change Management are as follows:

  1. Configure vCM Service Desk Integration. See the vCM documentation for details.
  2. Model your Change Management process using the ASM Core Workflow Template Administration.
  3. Map RFC Events through to your process using the ASM Core Integration Platform.
  4. Add Outbound Actions tasks to your process to Approve / Deny changes in vCM.

Modeling your Change Management Process

Your Change Management process should be modeled using the ASM Core Workflow Template Administration. A simple Change Management process can be seen below:

Create a Screen Set for your change process, and add the following extension fields to it. Display these fields as read only fields in your Request Details screen within that Screen Set.

Field

Data Type

VCM GUID

Text

VCM Notes

Text Area

VCM Type

Text

VCM Run Now

Checkbox

VCM Run Date Time

Date

Mapping RFC Events

The ASM Core Integration Platform should be used to map the receipt of vCM RFC Events onto the initiation of a request:

 

All other Incoming Transactions should be configured to Take No Action as follows:

 

It is recommended to set up the following incoming field mappings:

ASM Core Request Attribute

VCM Event Source

Update

VCM GUID

RFC Event GUID

Always

VCM Notes

Notes

Always

VCM Type

Type

Always

VCM Run Now

Run Now

Always

VCM Run Date Time

Run Time

Always

Request CIs

Machine CIs

Always

The mapping of the GUID is important as this is needed to approve or deny the change. The mapping of the Machine CIs is important as it allows impact analysis to be performed.

Approving / Denying Changes

At appropriate points in your ASM Core Change Management process, you should insert Outbound Action tasks that approve or deny changes. The only important field to map is the RFC Event GUID as follows:

The RFC No field will be automatically populated with the ASM Core request number (eg: Request#123). It is possible to overwrite this default format by providing an alternative mapping for this field (eg: RFC352).

The RFC Notes field can also optionally be mapped to pass additional information back to vCM.